home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / rs232.exe / RS232.DOC < prev   
Text File  |  1993-05-03  |  47KB  |  1,083 lines
  1.  
  2.  
  3.  
  4.                           RS232.C User Documentation
  5.                           copyright C. Karcher 1992,93
  6.  
  7.  
  8.  
  9. >   About RS232.C:
  10.  
  11.     RS232.C was written to provide all of the basic functionality needed
  12.     to employ serial I/O in any application written with Borland 'C'
  13.     language compilers.  Some features are:
  14.  
  15.     1. Ease of use.  No assembly language or library files are used and a
  16.     simple "#include" statement is all that is required to access all of
  17.     the functions provided.
  18.  
  19.     2. Both input and output are buffered and interrupt driven for
  20.     efficiency.
  21.  
  22.     3. Serial ports 1 - 4 are supported on PC, AT and PS/2 compatibles.
  23.     Chained interrupts used on port 3 and 4 are allowed for so as not to
  24.     interfere with devices such as a mouse or printer.  Transmission
  25.     speeds of 110 to 115200 baud are available.
  26.  
  27.     4. Detection and utilization of hardware buffered UARTs (NS16550AF
  28.     etc.) found in some machines is automatic.
  29.  
  30.     5. Interrupt driven hardware and XON/XOFF flow control is provided for.
  31.  
  32.     6. All source code is included.  RS232.C can be used with all memory
  33.     models.
  34.  
  35.  
  36.     This is user supported software and may be distributed freely in a
  37.     whole and unmodified state.  It may be used in part or wholly, free of
  38.     royalty, to develop any commercial applications provided that the
  39.     developer has registered RS232.C.  Registration entitles the developer
  40.     to any future enhancements or upgrades which may be released.
  41.     Registration also includes technical support as far as can be provided
  42.     via mail, telephone or electronic messaging.  To register RS232.C,
  43.     send a check or money order for $20.00 to:
  44.  
  45.          Chris A. Karcher
  46.          9537 Evanston Ave. N.
  47.          Seattle WA 98103-3131
  48.  
  49.     The author may be contacted by mail at the above address, by telephone
  50.     at (206)789-7945 or via Compuserve EMAIL to user ID 76406,536.
  51.  
  52.     The author of RS232.C makes no expressed or implied warranty of any
  53.     kind with regard to the software or accompanying documentation.  In no
  54.     event shall the author be held liable for incidental or consequential
  55.     damages in connection or arising out of performance or use of any part
  56.     of this software.
  57.  
  58.     The distribution should include the following files:
  59.  
  60.         RS232.C   - serial communication routines source code
  61.         RS232.DOC - documentation (this file)
  62.         RS_DEMO.C - sample program demonstrating RS232.C
  63.  
  64. >   Why use RS232.C?
  65.  
  66.     Borland's C compilers (and probably all DOS based C compilers) do
  67.     provide some basic support for serial communications but that support
  68.     makes use of calls to BIOS routines only.  The BIOS serial routines
  69.     are adequate only for the slowest of transmission speeds and do not
  70.     exploit all of the capabilities of the hardware found in PC's.  If
  71.     efficient serial communication is required, the programmer must
  72.     provide all of the low level software.  RS232.C does just that by
  73.     taking care of all the low level details and providing the programmer
  74.     with all the high level functions needed for efficient serial I/O.
  75.  
  76. >   How to use RS232.C:
  77.  
  78.     All that is required to use RS232.C is to include it in your source
  79.     code.  The simplest way to do that is with a compiler '#include'
  80.     directive, treating RS232.C just as you would a header file.  Having
  81.     done that, three basic steps are all that are required to perform
  82.     serial I/0:
  83.  
  84.          1. Allocate memory for input and output buffers.  (It can be pre-
  85.          allocated at compile time or allocated via some memory
  86.          allocation function like malloc at runtime.)
  87.  
  88.          2. "Open" the port with the function rs_initport, using the
  89.          desired communication parameters.
  90.  
  91.              perform I/O with functions provided
  92.                 .     .    .      .        .
  93.                 .     .    .      .        .
  94.                 .     .    .      .        .
  95.  
  96.          3. "Close" the port when finished performing I/O with the
  97.          function rs_close before ending the program.
  98.  
  99.     The file RS_DEMO.C, included with the distribution, is a sample
  100.     terminal program demonstrating most of the functions available with
  101.     RS232.C.
  102.  
  103.     The following code demonstrates an extremely simple but functional
  104.     program which turns a PC into a dumb terminal capable of communicating
  105.     with a modem or another computer:
  106.  
  107.      /*
  108.        TERM: a light weight dumb terminal program to demonstrate rs232.c
  109.        C. Karcher
  110.      */
  111.  
  112.     #include<conio.h>
  113.     #include"src\rs232.c"       /* include rs232 variables and functions */
  114.  
  115.     main()
  116.     {
  117.  
  118.        int key = 0;
  119.        char input_buffer[1024],output_buffer[1024]; /* allocate buffers */
  120.  
  121.        /* open COM port 1 with 2400 baud, no parity, 8 data bits, 1 stop bit,
  122.           a 1024 byte input buffer and a 1024 byte output buffer */
  123.  
  124.        if(rs_initport(RS_PORT1,RS_B2400,RS_NOPAR,RS_DBIT8,RS_SBIT1,
  125.                              1024U,input_buffer,1024U,output_buffer) > 0)
  126.          cprintf("Terminal mode active - press escape to exit\r\n");
  127.        else{
  128.          cprintf("Unable to open COM port\r\n");
  129.          return 0;
  130.          }
  131.  
  132.       /* turn on Data Terminal Ready */
  133.       rs_modctrl(RS_WRTMCR,RS_MCRDTR,RS_LINON);
  134.  
  135.       /* display any characters received and send any keystrokes typed until
  136.          escape is pressed */
  137.       do{
  138.         if(rs_inrcvd())                 /* if a character has been received */
  139.           putch(rs_getbyt());           /*    display it */
  140.         if(rs_keyhit())                 /* if a key has been pressed */
  141.           rs_sndbyt((key = getch()));   /*    send it */
  142.         }while(key != 27);              /* if the key pressed was ESC, end */
  143.  
  144.       /* turn off Data Terminal Ready */
  145.       rs_modctrl(RS_WRTMCR,RS_MCRDTR,RS_LINOFF);
  146.  
  147.       /* close the port and exit */
  148.       rs_close();
  149.       return 0;
  150.  
  151.     } /* end TERM */
  152.  
  153. >   RS232.C Functions:
  154.  
  155.     The following is a list of the functions contained in RS232.C and a
  156.     brief explanation of the purpose of each one.  A detailed description
  157.     of each function and it's use follows:
  158.  
  159.     rs_initport - Prepares a COM port for use.
  160.     rs_sndbyt   - Sends a single byte.
  161.     rs_sndstr   - Sends a string of bytes.
  162.     rs_getbyt   - Gets a single byte.
  163.     rs_getstr   - Gets a string of bytes.
  164.     rs_inrcvd   - Returns number of bytes which been received.
  165.     rs_outfre   - Returns amount of free space remaining in output buffer.
  166.     rs_error    - Returns code for last error detected.
  167.     rs_modctrl  - Controls or returns status of modem control lines.
  168.     rs_break    - Sends break to remote equipment.
  169.     rs_clrout   - Clears output buffer.
  170.     rs_clrin    - Clears input buffer.
  171.     rs_keyhit   - Determines if a key has been pressed.
  172.     rs_timer    - Times events or operations.
  173.     rs_setflow  - Establishes or returns status of flow control.
  174.     rs_close    - "Closes" port prepared by rs_initport.
  175.  
  176. >   Function Reference: (Note: The pre defined constants shown in
  177.                          parentheses with some of the function argument
  178.                          descriptions or return value descriptions are
  179.                          defined in RS232.C and may be used for
  180.                          convenience.)
  181.  
  182.   >   rs_initport:
  183.  
  184.     >   Purpose:
  185.           Prepares a COM port for use.
  186.  
  187.     >   Prototype:
  188.           int rs_initport(char port, long baud, char parity, char data_bits,
  189.                          char stop_bits, unsigned in_buf_size, char *in_buf,
  190.                          unsigned out_buf_size, char *out_buf);
  191.  
  192.     >   Arguments:
  193.            port: Character indicating which port to use.  May be one of
  194.                  the following:
  195.                    '1' (RS_PORT1) - COM port 1
  196.                    '2' (RS_PORT2)
  197.                    '3' (RS_PORT3)
  198.                    '4' (RS_PORT4) - COM port 4
  199.            baud: The long value indicating the baud rate.  Can be any of
  200.                  the following:
  201.                    110L (R